Almathera Ten Pack 3: CDPD 3

home *** CD-ROM | disk | FTP | other *** search

/ Almathera Ten Pack 3: CDPD 3 / Almathera Ten on Ten - Disc 3: CDPD3.iso / scope / 176-200 / scopedisk189 / dr-13 / dr.doc < prev next >

Wrap

Text File | 1995-03-19 | 25KB | 461 lines

DR (release 1.3) What we got here is Yet Another CLI Directory Listing Command, called Dr (pronounced "dr") because it leaves out icons. (Like, the missing I in Dir stands for icon...? never mind.) It is a fast and full featured program which is superior to all of the ten other Amiga directory listers I've tried. I couldn't live without it. Even its half-finished versions were preferable to Dir. The features it offers are: + By default, .info files are not mentioned in the output. Instead, it shows you which files have xxxxx.info files associated with them by writing their names in orange (or whatever you have set color 3 to be). Any xxxxx.info file that is not associated with a regular file or directory is shown normally, e.g. Disk.info. You can see all .info files normally with the -I option. + It is fully reentrant and reexecutable. The "pure" bit is set. + It is about as fast as a directory listing program can possibly be on the Amiga. (Which is still slow.) With well-filled floppies, Dr is frequently three times as fast as Dir ...other "fast" listers usually get about half that much improvement, and are usually less reliable besides. Under the Fast File System, there is much less difference, but Dr still has a slight edge. The guy who wrote NewList 4.5 claimed it was faster than Dr ... and it WAS faster than Dr 1.2 in this one case (scanning one FFS directory without recursive descent). But it is slower than Dr 1.3! + When recursively showing contents of subdirectories with the -R option, Dr's speed advantage increases further. Even with the Fast File System 25% to 75% speed improvement is common. Apparently, the more fragmented your disk is, the bigger the difference. + New in release 1.3: You can format the output so as to put the filenames into some context (like List LFORMAT but better), for instance generating an AmigaDOS command for each filename. It can either write out this formatted output, or execute it as a command, or do both with different formats. + It arranges the output in a variable number of columns, with spacing based on both the length of the longest filenames and the width of the window. It assumes a width of 77 when output is not going to a CON: window. By default, it sorts the entries in columns, not in rows; it's easier to find things alphabetically that way (try it out if you don't think so). The -H option makes it sort in rows. + It handles AmigaDOS wildcard patterns, like #?.(c|o) to list all xxxxx.c and xxxxx.o files. And if an actual directory has a name with pattern characters in it, like maybe a directory called "Doesn't-work?", it will list that directory instead of expanding the pattern. You can force it to expand by adding an extra percent sign to the pattern, so it doesn't match the name. New in 1.3: You can show all files that do NOT fit a pattern by putting a ~ at the beginning of it, e.g. dr foo/~#?.o shows all files in foo that do not end with .o; a ~ in the middle of a pattern has no special meaning. + It can sort alphabetically (the default) or chronologically (newest last) with the -C option. + It has an option (-O) to list each filename on a separate line as a complete pathname. This is useful for generating input to other programs. (The -F option is useful for this.) Files are sorted by disk address when you use this. This makes the list more efficient for other programs to process, sometimes. + It can list the size of each file in bytes with the -S option, or list complete information about each file and directory (size, protection, datestamp, filenote) like the List program with the -L option. -L is automatic if the argument you give it is the name of a single file instead of a directory. The -X option makes it give this information about a directory instead of showing that directory's contents. + The -U option makes it like "du", showing only disk space consumption. Typically you would combine it with -R. Use "alias du Dr -ur []". + New in release 1.3: the -A and -B options let you select files and dirs by age, and the -K option shows their disk addresses. Since release 1.2: the -P option makes it show only files and dirs that have a certain protection bit set or clear. + It uses a significant amount of memory, but if that much isn't available, it won't fail. (Well hardly ever...) It will simply work slower. When there's only a little extra room, it will work slightly faster than Dir. Release 1.3 avoids hogging the last of the memory just to be faster. + And last but certainly not least, it's public domain and the source code is provided. This includes the fast directory scanning routines FastExamine and FastExNext, which many programs may find useful since they are almost compatible with regular Examine and ExNext. See the file FastExNext.doc. CREDIT: the pattern matching code is PatMatch by Jeff Lydiatt, available on Fish disk 85, modified to be reentrant. Directory names are listed before file names, separated with a line of dashes, unless one or the other came up empty. Each directory name is followed by a slash. Only the name itself, not the slash, is orange if it has an icon. Things with associated .info files will be marked as such even if the .info file itself is excluded by the pattern, or by the -D or -A or -B options. If you list just a single file, it will check whether it has a .info file, unless you use the -I option. It does not check to see whether files with names ending in .info are actual valid icon files. Note that if the output is not a CON window, it doesn't show you which files had icons. It used to precede iconed names with a plus sign, but I concluded that this was not a win. If you want to find icons when you're saving the output, you just gotta use the -I option. Let me know if you want this changed. I heard that the numerous .info files are gonna disappear in AmigaDOS 2.0 anyway. That and FFS in ROM will eliminate most of my reasons for writing Dr in the first place. Sigh. So the 2.0 version of Dr might be two thirds the size of this one, but not really better than some other programs. Damn, a lot of the work I did in 1989 is turning out to be wasted. It would have been less wasted of course if I had gotten this thing out the door a year earlier ... "Dr: the Video Toaster of directory listers." Pattern wildcard characters are currently only recognized at the end of a pathname (that is, after the last slash or colon if any); you can't yet go "Dr #?/src/#?.c" to find all .c files in subdirectories named src. This ability will be added someday. If anybody cares. And maybe I'll improve the pattern parser itself so that it is tolerant of mismatched parens and such. And maybe make it able to use ~ (negation) inside the pattern instead of just at the beginning. USAGE: type Dr followed by zero or more file names, directory names, patterns, or options. The options in this version are: ? Briefly explain all of the options. -I List .info files like normal files instead of marking the other files they are associated with. -S Show the size of each file in bytes, and (new in release 1.2) totals. -C Sort chronologically (newest last) instead of alphabetically. -H Sort into rows instead of columns, if more than one column. -O Put each filename on a separate line, as a complete pathname. There is no other extraneous output and no sorting. Overrides -L, -S, -K, and -C. The beginning of the pathname is the directory arg you specified, not the absolute path. (The pathname has a maximum length of 300 characters.) -D Do not show file names, only subdirectory names. Cancels -F. -F Do not show subdirectory names, only file names. Cancels -D. -L Show sizes, protection bits, datestamps and filenotes like List. Overrides -S. Show total bytes/blocks used. -K Show the disk address (block key) of each file or directory, in square brackets. -X Show directory args as if they were in a -L listing, instead of scanning their contents. Ignored if -R or a pattern is used. Overrides -F, -D, and -P. -R Recursively show contents of all subdirectories. If you're going to descend a whole lot of levels (like more than about nine) you might need a bigger stack than the default 4K. It checks for adequate stack before entering each subdirectory. An 8K stack would let you go about 40 levels deep. -U Show only disk space consumed, and a count of files and directories, without listing any names. Overrides all other options except -R. -A# (example: -A30) Show all files dated within the last # days. The cutoff point would be midnight before the day # days ago. Thus -A0 would show today's files. -A not followed by a digit cancels. -B# (example: -B5) Like -A, but show all files more than # days old. Combining -A with -B uses a range of days, or excludes a range of days if the -A number is smaller (more recent) than the -B number. -P A bit more complicated than the options above; the letter P may have a tilde (~) after it, and immediately after that a letter, one of H, S, P, A, R, W, E, or D (lowercase OK). This letter represents a protection bit. If the tilde is between the P and the letter, Dr will show only files for which that protection bit is not set. If there is no tilde it will show only those for which it is set. For instance, to show all "pure" files, use -PP. To show all files which have not been backed up, use -P~A. Use -P with a space after it to cancel earlier -P options, making it ignore protection bits. For the bits R, W, E, and D, "set" means that the bit shows as present when you use List or Dr -L. The bit is actually a zero on the disk in this case. So for example -PD means show deletable files, -P~D means show files protected from deletion. Oh yeah ... you can use a caret (^) instead of a tilde (~) if you want. -[...format string...] Control the format of the output. For each file or directory to be listed, the text inside the brackets is written out followed by a newline. Substitutions are made on that text as follows: \n is replaced with a newline. \d is replaced with the name of the directory being searched. \f is replaced with the name of the current file or directory being listed, with no path in front. \/ is a slash unless the preceding character output was a slash, colon, double-quote or whitespace (or control char). For joining filenames onto directory names. \p is replaced with the full pathname of the current file or directory. \+ prevents newline at the end of each output. \ before anything else "quotes" it. Use \\ for \ and \] for ]. To cancel a previous format option, use -[]. Overrides -C, -S, -L, -O, and -K. Output is in disk block order as with -O. Note that whitespace and double-quotes inside -[...] are treated like any other characters, not as marking separate arguments to Dr. The output after substitutions is limited to 255 characters. -{... format string...} Like -[...], except it executes the result as a CLI command instead of just writing it out. (\} means }.) This is done in addition to, not instead of, normal output. So you can use both -[...] and -{...} at once with different formats. The output is done first, the command last. Use of -O is recommended if you don't use -[...]. If you want the files processed in sorted order, make sure to use either -H or -L, or the columnar sorting feature will mess it up. You can use -[\+] to suppress all output and just run commands. You can give several option letters after one dash, like "Dr -chs foo". The case of the letters doesn't matter. You can't combine option letters with format strings after one dash, though, and you can't (or at least shouldn't) put other options after a -P. Each option affects those files and directories that come after it on the command line, except that any options at the end, after the last filename, act as if they were entered at the beginning. Example: "dr foo -s bar" lists directory foo without showing sizes, and directory bar with sizes shown. If a directory name begins with a dash, put quotes around so that it isn't taken as options. If you give an option twice, the second one cancels the first. This means that if you make an alias like "alias list dr -lc []", you can make it sort alphabetically by saying "list -c". Or, you can show directory foo with sizes, and directory bar without sizes, with the command "Dr -s foo -s bar". (Note: since options at the end act like they are at the beginning, "Dr -s directory -s" will show the directory without the -s option!) Some examples of using format strings: to mark the files in directory foo as having been last updated yesterday, use Dr -o -{setdate "\p" yesterday} foo To rename all xxxxxxx.BAK files in directory foo to directory bar, use Dr -o -{rename "\p" as "bar/\f"} foo/#?.BAK To type out the contents of all files in foo with a header for each one, use Dr -[\n **** File \p -=>] -{type "\p"} foo You can execute more than one command for each file by putting \n in between them. But the complete text after all substitutions are made must be less than 256 characters long or Dr cannot execute it. If this happens it will write out a warning message and continue, and return 5 ("Warn") when it exits. If one of the commands returns a DOS error code it will stop, returning 10 ("Error"), and the DOS error code will be that which caused it to fail (like 205 for "object not found" or whatever). Some programs never set a DOS error code but indicate failure purely by their return value. But Dr cannot tell what the return code is, because it uses the DOS Execute function. To work around this, I am including a tiny program called R2E, which returns as its error code the value which the previous program gave as its return code. You would use it by adding "\n r2e" to the end of your -{...} format command. For instance, the rx program for running rexx scripts never sets a dos error code. You would use R2E on it like this: Dr -{rx whatever \n r2e} foo. Then if rx returned nonzero, r2e would cause Dr to stop at that point. Or if your command is "type \p", and you want Dr to stop if you stop Type with a control-C, you would use Dr -{type \p\n r2e} foo, because when Type is control-C'ed it returns 5 but no error code. For programs which don't react to control-C at all ... if you want to stop Dr, just keep banging control-C and sooner or later the signal will be heard by Dr instead of by the program being run. To make the -{...} option work most efficiently, there are certain steps you should take. One is this: If you are using AmigaDOS 1.3, make sure you are using version 1.3.2 of SetPatch, not 1.3.0! If you are using 1.2, get 1.3.2! Otherwise any program that uses the Execute function will reload C:Run from disk every time it's called. With 1.3.2 or newer AmigaDOS you can avoid that by making C:Run resident. Do this even if you don't use AmigaShell and don't make anything else resident. But it helps if you DO use AmigaShell (make L:ShellSeg resident as "CLI") and make resident if possible whatever commands you are executing. Make R2E resident if you ever use it; it's very small. If you don't use AmigaShell, copy the commands you are executing into ramdisk and run them from there. You can put a number after R2E to give it a "fail level". Return values below this number from the previous program will be returned as zero. Like, R2E 10 will report no error if the previous program returns 5, but will if it returns 10. The default "fail level" is 1. Neat trick: With Dr you can turn Lharc into a hard disk backup utility! Dr > Tempfile -orfip~a -{protect "\p" +a} disk:" This will write a list of all the files in disk: that have been altered since the last backup into Tempfile, and simultaneously mark all those files as archived. Then give the command Lharc -x -iTempfile a Vol:ArchiveName and it will archive all the files named in Tempfile into Vol:ArchiveName.LZH. You can continue Dr's command line onto multiple lines with a plus sign at the end of the line. It considers this newline to be just like a space. When you combine -R with a pattern, the complete contents of those outermost subdirectories whose names match the pattern will be shown. If you combine -R with -D or -F, all subdirectories will be listed, with only the directory or file contents of each, according to the option, shown. If you give more than one directory/pattern in the command line, each one's listing will be preceded by the name you gave, written like this: -- name -- unless you use -O or -[...] in which case the different listings will not be separated. If you give no directory or pattern, it lists the current directory, of course. Or you can specify the current directory as empty quotes: "". Note that the usage totals given at the end of a -S, -L, or -U output count only the files and dirs actually listed. If some of the files are marked as having icons, then the blocks used by those .info files are not counted (they are in the case of -U). Likewise things excluded by a pattern or -D or -F. But the total count of blocks used by all files and directories is given in parentheses. If you want complete totals for everything, use the -I option (if you're using -L and not -U) and don't use -D or -F or a pattern. Note that it does not actually count all the blocks in each file, it just guesses from the file's length. This is to avoid unnecessary disk access to read file extension blocks. There are occasionally files that are bigger than they look; fake files made to contain bad tracks are often like this. There is another version of Dr which is called Dr-S here. It is smaller and slower (and eats less ram as it runs) because it uses regular ExNext instead of FastExNext. To make it, compile dr.c with SMALLSLOW defined, and don't link with fastex.o; with make, just say "make s". (Use "make d" for the regular version.) Dr-S is actually faster in some cases when AddBuffers is of some use, e.g. if you list the same dir twice on the slow file system. It is about 5k bytes smaller than the regular Dr. Some users might prefer it, especially those who don't use floppy disks very much. I did not give it a BCPL style argument template for reasons of size. Almost 19k is plenty for a resident command. (That's sure a lot bigger than Dir or List, but it's smaller than both together, and it pretty much replaces both. It also replaces du (with the -ru options) and Donald Kindred's rls (with options -orf) and the SPAT and DPAT scripts -- see the replacement versions of those files distributed with Dr.) Maybe I should have used arp.library ... would use less memory *IF* you would routinely have that library loaded anyway. I did make sure that quoted quotes are done with *" instead of Manx's default "", and that quotes make -options be treated as directory names. Some other features I might add someday: -G: Show file's timestamp as age; days and hh:mm:ss before present. Some option to select whether "Today" etc. is used with -L? Handle patterns in the middles of paths, like foo/#?/src/#?.c Some way to cause a pattern at the end of the path to apply to files in all subdirectories scanned. That is, directorypath/?#?.(c|o) would now be essentially also equivalent to directorypath/#?/?#?.(c|o) and directorypath/#?/#?/?#?.(c|o), etc. Maybe a pattern that ends with :: would act this way. This would implicitly use -R descent. Make -P able to make a mask of several bits. I should make it able to output each filename as it scans it, with no sorting, like List. Especially with the -O and -{...} options. This would disable .info hiding and flexible column width. Use of asynchronous disk IO may be worthwhile with this. More flexible formatting options. Separate version for Dos 1.2? Translate it all into assembly?? The Amiga is now the fourth system I have written a directory lister for. First was TOPS-20 (one that showed only files that you are the owner of), next Kaypro II (fast, 2K long, sorted, showed size), third 4.2 BSD Un*#%$!x (like ls -ls but faster because don't look up group names, just indicate whether your group). So this one is like the crowning achievement of a great career in directory lister writing. There is now almost no use at all for any other directory lister, except maybe if you actually find Dir's interactive mode to be of any use. My original goal was just to produce an adequate alternative that left out .info files; my goal now is for Dr to be the best available. Dr is in the public domain, written by bbses: try Paul Kienitz Winners Circle 415-845-4812 6430 San Pablo ave. Triple-A 415-222-9416 Oakland, CA 94608 FAUG 415-595-2479 USA Feature suggestions and bug reports are appreciated. I think it's pretty bulletproof, but there might be some file devices it can't read properly, one never knows. Shareware incentive: anyone who sends in a financial contribution will receive... (drum roll) a nice thank-you note. Which is more than I've gotten from some of our better known hackers. If you want the source and didn't get it with the executable, you should be able to download it from any of those bbses. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - DIFFERENCES BETWEEN RELEASE 1.3 AND RELEASE 1.2: Sorting of names and elimination of matched .info's greatly sped up. Negative patterns with ~ in front added. -{...} and -[...] formatting options added. ForEvery no longer needed. -A and -B options added. -K option added. FastExamine makes sure there is some EXTRA memory (20K) that it probably won't need, before it goes into high speed ram-hog mode. Tested, but did not use, code to make FastExNext use asynchronous packets instead of ExNext() calls in the cases when it can't use its high speed code. I judge the speed improvement to be too small to justify the extra program size. See makefile. DIFFERENCES BETWEEN 1.2 AND 1.1: -P option was added. My god! I never noticed that the PatMatch functions I used were not reentrant! I now use a modified patmatch.c instead of the original. ForEvery (and Whichever just for the halibut) bundled with Dr. 1.2 has been redone into ANSI C. It's a bit smaller. By request, the -s option now reports totals like the -l option. The feature wherein recent files would show their dates as "Today" or "Wednesday" instead of the actual date has been removed. To get it back, recompile dr.c with the symbol WEEEEK defined. See makefile. I wrote, but did not use, code to show directory names in boldface or against a black background or both instead of above a line of dashes. See the makefile for how to compile this way. Oops, the -- Name -- thing between different command line args' output was not eliminated by -o as documented, in older versions. DIFFERENCES BETWEEN 1.1 AND 1.0: 1.0 gurued on many device drivers which did not support ETD_READ. 1.1 uses CMD_READ when ETD_READ fails, and the dumb mistake which caused a guru when it tried to report the error was fixed. IF YOU SEE A COPY OF 1.0 GET RID OF IT, IT'S NO GOOD! (This bug never showed up on my hardware.) 1.1 pays attention to the MaxTransfer mount parameter, and if it is an integral fraction of the track size it pretends that this fraction is a "track", otherwise (gotta fix this someday) falls through to ExNext. 1.0 did not check for adequate stack. 1.1 makes sure there is enough stack each time it descends another level with the -r option. 1.0 had a small bug in reporting .info files with the -o option.